Graphics Plus/Graphics Plus.iso/general/raytrace/dkb/dkbutdoc.zoo/utils.doc

Text File | 1991-06-09 | 14.2 KB | 317 lines

The DKBTrace Utilities
----------------------

In many cases, creating data files for DKBTrace is difficult and tedious.  To
help remedy this problem, We and various other people have developed some
utilities to create data files.  These utilities are described below.

As well, there are some utilities that perform operations on the image files
created by DKBTrace.  These utilities convert between various formats and
allow you to modify or merge output files together.  All in all there are
three major types of DKB utilities, I. Data File Creation, II. Output File
Manipulation, and III. Animation Utilities.

We'd like to thank all the people who wrote these utilities and sent them to
us.  If anybody else comes up with other utilities, please let us know and
we'll cheerfully include them in future distributions.

Some of these utilities are written in BASIC for IBM PC systems (Arrrggh! :-P).
As such,they are not easily portable from system to system.  We really wanted
to convert them all to C, but found that time was prohibitive.  If anyone wants
to try their hand at converting them to C, let us know and we'll post the C
versions.  They are all in Microsoft structured BASIC, which really isn't all
that far away from real C, anyway.


< I. >  Data File Creation Utilities

-------------------------------------------------------------------------------

The data creation utilities fall into two categories:  Those that convert from
some other format into DKB format, and those that generate DKB files using
algorithmic techniques.  These utilities are described below.

-------------------------------------------------------------------------------

1.)  SA2DKB

This program converts Sculpt-Animate 3D & 4D data files into DKB format.  It
currently only supports the basic triangles and textures. It doesn't support
smooth triangles (it treats them like normal triangles), light sources,
cameras, or floors.

(This utility was formerly called "Sculpt2DKB" but the IBM systems out there
kept calling it "SCULPT2D", then couldn't figure out what a 2D program had to
do with raytracing or what the nonexistent Amiga program called "Sculpt-2D"
was :-)

2)  DXF2DKB

This utility converts AutoCAD DXF (Drawing eXchange Format) files into
DKBTrace format scene description files.  It was written by Aaron Collins.  It
does not support all of the DXF primitives, but will suffice for simple
objects and scenes after EXPLODE'ing and DXFOUT'ing then in AutoCAD.

3)  ShellGen

ShellGen is a BASIC program written by Dan Farmer.  It's based on a short code
fragment from Clifford Pickover's book "Computers, Pattern, Chaos, and Beauty"
(St. Martin's Press).  This code fragment was reprinted in Ray Tracing News
Issue 3.3.

As far as I know, the BASIC program only works on IBM's.  It does, however,
allow you to change the parameters and see a quick outline of what the result
will look like.

For those people without IBM's, I've changed the original code fragment to at
least output a DKB-format file.  No user interface has been provided, however.
The file is called PICKSHELL.C and is included in this archive.

The file DKBSHELL.INC is included by the program at the top of each data file
it generates.  If you feel the VIEW_POINT or LIGHT_SOURCE definitions need
changing, go ahead.

4)  Twister

Twister is a C program written by Drew Wells (CIS 73767,1244).  It creates
data files for twisted shapes.  The program uses a text interface and prompts
the user with a question/answer format.

5)  Chem2DKB

Chem2DKB is an IBM BASIC program written by Dan Farmer.  It takes models
generated by the CHEM.EXE V.2.00 program written by Larry Puhl.

6)  Lissajou

This is an IBM BASIC program written by Dan Farmer.  It creates data files for
lissajous figures.  The basic algorithms were from Clifford Pickover.  See
Scientific American Jan. '91 and Omni Feb '90 for examples.

7)  3D2-DKB

This is a C program written by Steve Anger.  It takes a CAD-3D (Macintosh?)
.3D2 scene description data file and converts it to DKB format.  There was
an earlier program called 3D22DXF.BAS which performed nearly the same function,
but output Auto-CAD DXF files instead of DKB data files directly.  Light source
locations, ambient light levels and object color information are all converted.

8)  SplitDKB

This is a program for IBM PC's running DOS.  It works by generating a bunch of
batch files meant for breaking up a long-running data file to trace in several
parts for multiple machine execution.  It also generates a batch file that will
glue the partial output files together in the correct order when all are done.
It is written in IBM BASIC by Dan Farmer, based on an idea by Randy Antler.

9)  Diamond

This is an IBM BASIC program written by Ken Koehler.  It generates a DKB data
file that describes the 3-D geometry of a faceted-cut gem stone (i.e. diamond).
It will generate an entire runnable DKB data file including light sources and
view points.  It quickly displays an outline of the diamond shape it is about
to create in graphics mode.  Many parameters are user-definable, such as the
height, width, number of sides, etc.

10) Gear

This is an IBM BASIC program written by Ken Koehler.  It generates a DKB data
file that describes the 3-D geometry of a toothed gear.  The gear may be solid-
centered with holes drilled in it, or spoked.  The teeth may be pointed or flat
(the "flat" options were commented out originally, so they may not work right).
It will generate a DKB data file with the gear shape DECLARE'd.  It quickly
displays an outline of the gear shape it is about to create in graphics mode.

11)  TCE  (The Color Editor)

This is an IBM BASIC program written by Dan Farmer.  This is an interesting
color preview/mixing program.  It will as for the name of a color definition
file (which we all now know is called "colors.dat", right?!?!?)  and allow you
to browse through the file and display the colors therein, preview how they
will look (approximately) when projected onto a shaded sphere, and allow you
to change the R-G-B levels and create new colors for the file.  Very nice
bolt-down menus.

12)  Font2Dat

This is an IBM BASIC program written by Ken Koehler.  It will take an IBM
screen font file (type .FNT or .SET) and convert them to DKB 3-D data files
using spheres, boxes, squares, or dots to represent each pixel in each source
character.  It generates either a large data file containing all the chars or
individual data files, one file per char, at the user's request.  The file
ROMAN.FNT is an example font file you can use to try it.

13)  Star

This is an IBM BASIC program written by Ken Koehler.  It draws an n-pointed
3-dimensional star figure, and gives a quick preview of what it looks like
on the screen in graphics mode.  It outputs a COMPOSITE object in a DKB
data file that needs to have a view point and light sources added, and the
star's color and texture need to be declared.


< II. >  Output File Manipulation Utilities

-------------------------------------------------------------------------------

These utilities perform some useful manipulations on the dump format and Targa
format output files from DKBTrace.  I'd like to thank the people who wrote
these utilities and provided them for general distribution.

-------------------------------------------------------------------------------

1)  dump2i24   (DumpToIFF24)

This program was written by Helge E. Rasmussen ([e-mail]).  It converts
the dump format files produced by DKBTrace into 24-bit IFF format files.
These files can then be read by a variety of programs including "The Art
Department" by ASDG.

2)  catdump

This utility was written by Ville Saari [e-mail] (and copyright
by the Ferry Island Pixelboys.)  It takes two or more partially rendered files
in DKBTrace's dump format and merges them into one file.  This is useful for
all sorts of things like rendering different parts on different computers and
combining the results.

NOTE:  Be careful if you combine pictures produced on different systems.  If
the random number generator works differently between the two systems, the
textures may look completely different from one another.  So long as you
use the same executable, you should be fine.

3)  combdump  (combine dump)

This utility was also written by Ville Saari.  It takes two images generated
with DKBTrace with slightly different viewpoints, and creates one dump-format
image file to be viewed with RED-BLUE or RED-GREEN 3D glasses.  The program
allows you to compensate for the exact filtering characteristics of your
glasses to get the best possible result.

4)  dump2mtv

This is yet another utility written by Ville Saari.  This one converts
DKBTrace dump format files onto MTV format used by the MTV and RayShade
raytracers.

5)  dump2raw

The dump2raw utility was written by Aaron Collins to convert the dump format
output of DKBTrace into three separate files for red, green, and blue.  On the
IBM, the extensions for these files are "r8", "g8", and "b8".  On the other
systems, they are "red", "grn" and "blu".

DKB Version 2.10 and later allows you to use the +fr option to output "raw"
format files directly without the need for a conversion program like this.

6)  halftga

The halftga utility (written by Aaron Collins) shrinks a Targa-format file to
exactly half its original size.  This file can then be converted into a GIF
image and used in an IMAGE_MAP statement.  For systems with little memory
available for imagemaps, this command can be a life-saver.

7)  gluetga

This utility (by Aaron Collins) is similar to catdump but works for Targa
format files.  It takes several partially-rendered Targa files and glues them
together into one image.

8)  tga2dump

This utility was written by Aaron Collins.  It converts Targa format 16, 24,
and 32 bit images into DKB's dump format for use in importing Targa files for
image-mapping textures in "true color" (24-bit).

9) ip2dkb

This utility was written by Frank P. Weed II.  It converts Amiga Digiview IP
format output files to DKB's dump format for use in importing IP files for
image-mapping.  Digiview IP uses a 2-million color range, which is converted
to the more common 16-million color (24-bit) range.


< III. >  Animation Utilities

-------------------------------------------------------------------------------

One of the most frequent questions I'm asked is whether or not DKBTrace
supports animation.  The answer is no, not directly.  However, I have made
some changes to the program to provide frame-to-frame consistency so you can
use it for animation if you want to.  The problem, then, is creating the data
files for each individual frame.  That's what this section is all about.

-------------------------------------------------------------------------------

1)  Anima

This is an IBM BASIC program written by Dan Farmer.  It will take a "skeleton"
data file with syntactic variables used (like %0, %1, etc.) and use "rules"
which dictate how the variables change over each frame.  The program will
stamp out a given number of DKB data files with the variables substituted for
the actual desired values, stepped in each data file according to the "rules".
The files ANIM1.DAT and ANIM2.DAT are a couple of example "skeleton" data files
you can use to try it.

2)  RayScene

Although RayScene is not being distributed with this raytracer, we thought we'd
at least mention it and tell you where you can get it.  RayScene is a program
that creates data files for DKBTrace based on a high-level (higher-level?)
description of the motion of the camera and the objects.  It was written by
Jari K{hk|nen ([e-mail]) and Panu Hassi ([e-mail]) and
is available by anonymous FTP from tolsun.oulu.fi (128.214.5.6) in the
directory /pub/rayscene or from iear.arts.rpi.edu in the directory
/pub/graphics/ray/rayscene.  Of course, it's also on the "You Can Call Me RAY"
BBS in the Chicago Area, [phone].

This explanation of RayScene was sent to me by Panu Hassi;

   "I've tried animation with DBW before DKBTrace2.0 was released.
    The procedure was this: First I wrote the first scene file, copied it
    for NUMBER_OF_FRAMES times and then edited some parts of those files
    to create movement etc.  If something went wrong (I accidentally edited
    wrong value etc), I had to edit all those scene files again to make the
    changes.  Not so nice if there are 100 files to edit...

    So a friend of mine, Jari K{hk|nen, and I decided to write RayScene to
    make that process even a little easier.  With RayScene the process
    goes like this:  you create a scene file and mark the places that
    should be changed with a variable, like:

    BOUNDED_BY
         SPHERE <0.0 0.0 0.0> #sphere_size# END_SPHERE
    END_BOUND

    Then you create another file where the values for these variables are
    listed.  Rayscene simply creates N scene files inserting current value of
    each variable to proper place.  That's all :D

    We have included couple of simple utilities that help with creating
    those variable values, but the original scene files are still created
    'manually'.  Still, the results have been really nice.  There are
    several animations for Amiga and PC in tolsun.oulu.fi."


< IV. >  Concluding Remarks

------------------------------------------------------------------------------

The IBM executable versions of the utilities are compiled with 8088/no 8087
flags given to the compiler for maximum portability.  If you REALLY must have
them operate a LITTLE quicker, you can change the IBM*.MAK files to use a
coprocessor and/or 286 opcodes, and then re-compile all of the "C" utilities.
For the most part the utilities are simple and small enough that they perform
adequately without really needing these optimizations.

Four semi-extraneous files are included:

    1) Dump2RGB.C is older version of Dump2RAW.C that uses more memory & less
       disk activity.
    2) CHEMCONV.C is a different (C instead of BASIC) IBM P.C. Chem V.2.00
       molecular modeler Data file generator (renamed from CHEM2DKB.C).
    3) PICKSHEL.C is the original C program that SHELLGEN.BAS is derived from,
       Clifford Pickover's seashell program (renamed from SHELLGEN.C).
    4) 3D22DXF.BAS is an older BASIC program that wrote DXF files.  3d2-dkb.c
       is by a different author, and converts 3d2 files to DKB files directly.